/**
 *	\file
 *	\brief it contains functions to handle in a better and safe
 *	way the memory
 *
 *	Memory Tools goal is to provide services to handle the memory.
 *	The worst thing to do normally is continue to malloc memory and forget to free it:
 *	this is called <b>memory leak</b>. Memory leak can drop program memory performance.
 *	Worst of all, memory leak are difficult to debug; for this very problem memory tools
 *	offers 3 main functions:
 *	\li mallocMemory() which allocates new memory;
 *	\li freeMemory() which free used memory;
 *	\li freeMemoryArray() which free an array from memory;
 *	\li getMemoryAllocated() which return the number of byte allocated;
 *	\li testMemoryLeak() which determine if the developer has forgotten some object in memory;
 *
 *	For example assume you want to start to keep trace of memory allocation. First of all you have to call
 *	startMemoryObservation(). Then you can alloc and/or free memory with mallocMemory() and/or freeMemory(). Finally
 *	you can test if there are some object waiting to be freed with testMemoryLeak(). Here an example:
 *	\code{.c}
 *		startMemoryObservation();
 *		pstudent=(Pstudent)mallocMemory(sizeof(Student),"not enough space; malloc#34");
 *		...
 *		//some actions here
 *		...
 *		freeMemory(pstudent);
 *		testMemoryLeak(stdout);
 *	\endcode
 *
 * 	\date Jul 20, 2013
 * 	\author koldar
 * 	\version 1.0
 */

#ifndef MEMORY_TOOLS_H_
#define MEMORY_TOOLS_H_

#include <stdio.h>

int __memory_allocated__;

/**initialize support variable to start recording the state of the memory. You <b>have</b> to call this function
 * before calling other <i>functions</i> of this library, like mallocMemory().
 *
 */
void resetMemoryObservation();

/**execute a safe allocation in memory. Moreover it updates an internal table to keep trace of the memory allocated:
 * in this way memory leaks can be easily tested. If the memory allocation fails (for example because there is no enough memory)
 * the errormessage is printed on the stderr
 *
 * \pre
 *  \li errormessage non NULL
 * \post
 *  \li a new block as big as memoryToMalloc is allocated in memory. It <b>must</b> be deallocated with freeMemory() or freeMemoryArray()
 *
 * @param memoryToMalloc represents the number of byte to store in memory
 * @param errormessage indicates the errore that must be printed on stderr if there is no enough space in memory
 * @return a pointer to the object allocated in memory
 */
void* mallocMemory(int memoryToMalloc,const char* errormessage);

/**free some memory pointed by objectToFree. Moreover it updates an internal table to test memory leaks.
 *
 * \pre
 *  \li objectToFree non NULL
 *  \li objectToFree allocated using malloMemory
 *  \li memoryToFree is non negative
 * \post
 *  \li the memory pointed by objectToFree is set free
 *
 * @param memoryToFree the size of the memory to deallocate
 * @param objectToFree represents the object to free
 */
void freeMemory(int memoryToFree,void* objectToFree);

/**prints on the file f the space allocated  in memory using mallocMemory().
 * testMemoryLeak() prints some data:
 * \li the total number of bytes allocated: if this number is not 0 then there is some memory leak somewhere;
 *
 * Just before the program ends call this procedure: if the number of bytes is 0 then you have no memory leaks.
 *
 * @param f the file to write on the data
 */
void testMemoryLeak(FILE* f);

/**
 *
 * @return the space allocated in the memory up till now
 */
int getMemoryAllocated();

#endif /* MEMORY_TOOLS_H_ */
